home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1996 #15 / Monster Media Number 15 (Monster Media)(July 1996).ISO / prog_c / cscop122.zip / CSCOPE.DOC < prev    next >
Text File  |  1996-05-01  |  43KB  |  1,559 lines

  1.  
  2.  
  3.                                                                              
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                     c-scope
  16.  
  17.  
  18.                                    C program
  19.  
  20.                                  analysis tool
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.                                  User's Manual
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.                                  JAYAR Systems
  50.                               253 College Street
  51.                                    Suite 263
  52.                                Toronto, Ontario
  53.                                Canada   M5T 1R5
  54.                                 (416) 751-5678
  55.         e-mail: jrsys@io.org    World Wid Web: http://www.io.org/~jrsys
  56.  
  57.  
  58.                                                                              
  59.  
  60.  
  61.  
  62.  
  63.                                                                              
  64.  
  65.  
  66.                                     LICENSE
  67.  
  68.         The license for the Shareware evaluation (trial use) version of
  69.   c-scope is contained in the file LICENSE.DOC. This file has been included
  70.   for your convenience as an appendix to this manual.
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.                                    WARRANTY
  79.  
  80.         The Shareware evaluation (trial use) version of c-scope is provided
  81.   AS IS. JAYAR Systems MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED,
  82.   INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY AND/OR
  83.   FITNESS FOR A PARTICULAR PURPOSE.
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.                                 SUPPORT POLICY
  92.  
  93.         JAYAR Systems provides free support for this product. We will answer
  94.   questions and fix serious bugs. If you have any questions about or problems
  95.   with using this product, give us a call at the number on the front cover of
  96.   this manual. Or, if you are not in a rush, send us a letter.
  97.  
  98.         We would also appreciate hearing from you if you have any comments or
  99.   suggestions for improvements.
  100.  
  101.  
  102.  
  103.  
  104.                      _______                    
  105.                 ____|__     |               (R) 
  106.              --|       |    |-------------------
  107.                |   ____|__  |  Association of   
  108.                |  |       |_|  Shareware        
  109.                |__|   o   |    Professionals    
  110.              -----|   |   |---------------------
  111.                   |___|___|    MEMBER           
  112.  
  113.  
  114.                   c-scope Copyright (C) 1991-96 JAYAR Systems
  115.                               All Rights Reserved
  116.  
  117.  
  118.                                                                              
  119.  
  120.  
  121.  
  122.  
  123.                                                                              
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.                                    CONTENTS
  132.  
  133.  
  134.  
  135.   1      Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .    1
  136.   2      What c-scope does . . . . . . . . . . . . . . . . . . . . . . .    2
  137.   3      Using c-scope . . . . . . . . . . . . . . . . . . . . . . . . .    9
  138.           1 Installing c-scope . . . . . . . . . . . . . . . . . . . . .    9
  139.           2 Running c-scope  . . . . . . . . . . . . . . . . . . . . . .    9
  140.                1 Circular Function References  . . . . . . . . . . . . .   10
  141.           3 Ignoring functions . . . . . . . . . . . . . . . . . . . . .   10
  142.           4 Function declarations  . . . . . . . . . . . . . . . . . . .   11
  143.   4      Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
  144.           1 Non-standard function types  . . . . . . . . . . . . . . . .   12
  145.           2 Preprocessor . . . . . . . . . . . . . . . . . . . . . . . .   12
  146.           3 Function pointers  . . . . . . . . . . . . . . . . . . . . .   12
  147.   A      Error messages  . . . . . . . . . . . . . . . . . . . . . . . .   14
  148.   B      License . . . . . . . . . . . . . . . . . . . . . . . . . . . .   16
  149.   C      Trial Use License:  . . . . . . . . . . . . . . . . . . . . . .   17
  150.   D      Limited Distribution License: . . . . . . . . . . . . . . . . .   18
  151.   E      Definition of Shareware . . . . . . . . . . . . . . . . . . . .   20
  152.   F      How to Register . . . . . . . . . . . . . . . . . . . . . . . .   21
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.                                       iii                                    
  179.  
  180.  
  181.  
  182.  
  183.                                                                              
  184.  
  185.  
  186.  
  187.  
  188.  
  189.                                 1 Introduction
  190.  
  191.  
  192.   c-scope is an analysis tool for C programs. It shows you what functions are
  193.   contained in a program and which functions they reference. This information
  194.   is provided in several easy-to-use formats. In addition, the registered
  195.   version of c-scope computes and reports a number of software complexity
  196.   metrics for each function and provides an inverse function reference
  197.   ("called by") report.
  198.  
  199.         The program to be analyzed may be contained in one file, or spread
  200.   across many files, as is typical with C programs.
  201.  
  202.         It is possible with c-scope to get detailed information on all of the
  203.   inter-function references, or just on those that you are interested in.
  204.  
  205.         The analysis provided by c-scope is ideal for understanding or
  206.   documenting the structure and operation of a large C program, whether it is
  207.   a program you wrote or one that you inherited.
  208.  
  209.         Using c-scope is simple and is described in the following sections of
  210.   the manual. Section 2 describes c-scope's capabilities by working through a
  211.   short example. Section 3 shows you how to use c-scope. And Section 4
  212.   provides a few notes on using c-scope.
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.                                        1                                     
  239.  
  240.  
  241.  
  242.  
  243.                                                          What c-scope does  2
  244.  
  245.  
  246.  
  247.  
  248.  
  249.                               2 What c-scope does
  250.  
  251.  
  252.   The easiest way to explain what c-scope does is to work through an example.
  253.   For illustration purposes we will use the following simple example program
  254.   (the RPN desk calculator program, borrowed from K & R) and analyze it with
  255.   c-scope. The program consists of five functions, in three files.
  256.  
  257.         File DCALC.C in Figure 1 contains the main program, main(), file
  258.   STACK.C in Figure 2 contains the functions push(), pop() and clear() and
  259.   file GETOP.C in Figure 3 contains function getop().
  260.  
  261.         When c-scope analyzes a program it produces four reports which are
  262.   printed on stdout:
  263.  
  264.     o A Function Location report. For each function defined in your program
  265.       (i.e., has source code), c-scope lists the function (functions are
  266.       listed alphabetically), the name of the file the function is contained
  267.       in, and the line number in the file where the function is defined; for
  268.       our example program:
  269.  
  270.               FUNCTION LOCATION
  271.  
  272.               Function              File                  Line No.
  273.               --------------------  --------------------  --------
  274.               clear                 STACK.C                     34
  275.               getop                 GETOP.C                      6
  276.               main                  DCALC.C                      7
  277.               pop                   STACK.C                     22
  278.               push                  STACK.C                     10
  279.  
  280.     o A File Contents report. This is similar to the Function Location
  281.       report, but for each file the functions defined in it are listed. File
  282.       names are printed in the order determined by the contents of the file
  283.       SOURCE.DAT (discussed later in Section 3.2):
  284.  
  285.               FILE CONTENTS
  286.  
  287.               File                  Function
  288.               --------------------  --------------------
  289.  
  290.               GETOP.C               getop               
  291.  
  292.               DCALC.C               main                
  293.  
  294.               STACK.C               push                
  295.                                     pop                 
  296.  
  297.  
  298.                                                                              
  299.  
  300.  
  301.  
  302.  
  303.                                                          What c-scope does  3
  304.  
  305.  
  306.                                     clear               
  307.  
  308.     o A Function Calls report. For each function defined in the program
  309.       (i.e., whose source code is available), an alphabetical list of the
  310.       functions called by that function are listed. c-scope recognizes a
  311.       function call if it occurs in the body of the function or in an
  312.       initialization statement. Functions which do not reference any other
  313.       functions are listed as referencing function void (e.g., function
  314.       clear() in our example):
  315.  
  316.               FUNCTION CALLS
  317.  
  318.               Function              Calls function
  319.               --------------------  --------------
  320.  
  321.               getop                 getc                
  322.                                     ungetc              
  323.  
  324.               main                  atof                
  325.                                     clear               
  326.                                     getop               
  327.                                     pop                 
  328.                                     printf              
  329.                                     push                
  330.  
  331.               push                  clear               
  332.                                     printf              
  333.  
  334.               pop                   clear               
  335.                                     printf              
  336.  
  337.               clear                 void
  338.  
  339.     o A Static Calling Tree. Starting with the main() function, all the
  340.       functions it calls, and all the functions called by those functions,
  341.       etc. are listed in a tree format:
  342.  
  343.               STATIC CALLING TREE
  344.                  0. main
  345.                     1. atof[E]
  346.                     1. clear
  347.                     1. getop
  348.                        2. getc[E]
  349.                        2. ungetc[E]
  350.                     1. pop
  351.                        2. clear
  352.                        2. printf[E]
  353.                     1. printf[E]
  354.                     1. push
  355.                        2. clear
  356.  
  357.  
  358.                                                                              
  359.  
  360.  
  361.  
  362.  
  363.                                                          What c-scope does  4
  364.  
  365.  
  366.                        2. printf[E]
  367.  
  368.       A level number is printed beside each function name to aid
  369.       interpretation. main() is at level 0, all the functions called by
  370.       main() are at level 1, and so on. The functions referenced by a higher
  371.       level function are listed alphabetically.
  372.  
  373.       Multiple references to a function are ignored--main() in our example
  374.       calls push() and pop() several times, but they only appear in the tree
  375.       once. If a function appears more than once in the tree, because it is
  376.       called by more than one function, the function is only expanded the
  377.       first time, to reduce the amount of output. Including the -e option
  378.       will force c-scope to expand all references though.
  379.  
  380.       The letter [E] following a function name means the function is defined
  381.       externally--its source code was not available. The letter [R] is also
  382.       printed for functions that are called recursively.
  383.  
  384.       If a main() function is not defined, a static calling tree is not
  385.       produced.
  386.  
  387.         The registered version of c-scope also produces a Function Complexity
  388.   report. For each function in your program c-scope lists the function name,
  389.   the number of source lines in it, the number of statements in it and the
  390.   number of while, for, switch and if statements:
  391.  
  392.           SOFTWARE COMPLEXITY METRICS
  393.  
  394.           Function               Lines  Stmts   whl   for   swc     if
  395.           --------------------  ------ ------  ----  ----  ----  -----
  396.           clear                      4      1     0     0     0     0
  397.           getop                     35     16     2     2     0     6
  398.           main                      35     21     1     0     1     1
  399.           pop                       10      4     0     0     0     1
  400.           push                      10      4     0     0     0     1
  401.  
  402.         In addition, the registered version of c-scope generates a Functions
  403.   Called report. Every function that is called by one of the functions
  404.   defined in your program (i.e., whose source code is available), is listed,
  405.   along with all the defined functions that call it. This is convenient for
  406.   locating where a given function is referenced. This report also includes
  407.   names of functions that are unreferenced--that is, those that are not
  408.   called by any other function.
  409.  
  410.   FUNCTIONS CALLED
  411.  
  412.   Function              Called by function
  413.   --------------------  ------------------
  414.  
  415.   atof [E]              main
  416.  
  417.  
  418.                                                                              
  419.  
  420.  
  421.  
  422.  
  423.                                                          What c-scope does  5
  424.  
  425.  
  426.  
  427.   clear                 main
  428.                         push
  429.                         pop
  430.  
  431.   getc [E]              getop
  432.  
  433.   getop                 main
  434.  
  435.   pop                   main
  436.  
  437.   printf [E]            main
  438.                         push
  439.                         pop
  440.  
  441.   push                  main
  442.  
  443.   ungetc [E]            getop
  444.  
  445.         See Appendix C for information on registering your version of
  446.   c-scope.
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.                                                                              
  479.  
  480.  
  481.  
  482.  
  483.                                                          What c-scope does  6
  484.  
  485.  
  486.   #include <stdio.h>
  487.  
  488.   #define MAXOP 20
  489.   #define NUMBER '0'
  490.   #define TOOBIG '9'
  491.  
  492.   main()
  493.   {
  494.     int type;
  495.     char s[MAXOP];
  496.     double op2, atof(char *), pop(void), push(double);
  497.     void clear(void);
  498.     int getop(char *s, int lim);
  499.  
  500.     while ((type = getop(s, MAXOP)) != EOF)
  501.       switch (type)
  502.       { case NUMBER: push(atof(s));
  503.                      break;
  504.         case '+':    push(pop() + pop());
  505.                      break;
  506.         case '*':    push(pop() * pop());
  507.                      break;
  508.         case '-':    op2 = pop();
  509.                      push(pop() - op2);
  510.                      break;
  511.         case '/':    op2 = pop();
  512.                      if (op2 != 0.0)
  513.                        push(pop() / op2);
  514.                      else
  515.                        printf("zero divisor popped\n");
  516.                      break;
  517.         case '=':    printf("\t%f\n",push(pop()));
  518.                      break;
  519.         case 'c':    clear();
  520.                      break;
  521.         case TOOBIG: printf("%.20s ... is too long\n",s);
  522.                      break;
  523.         default:     printf("unknown command %c\n", type);
  524.                      break;
  525.       }
  526.   }
  527.  
  528.  
  529.  
  530.  
  531.   Figure 1: File DCALC.C which contains function main().
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.                                                                              
  539.  
  540.  
  541.  
  542.  
  543.                                                          What c-scope does  7
  544.  
  545.  
  546.   #include <stdio.h>
  547.  
  548.   #define MAXVAL 100
  549.  
  550.   int sp = 0;
  551.   double val[MAXVAL], push(double f), pop(void);
  552.   void clear(void);
  553.  
  554.  
  555.   double push(double f)
  556.   {
  557.     if (sp < MAXVAL)
  558.       return(val[sp++] = f);
  559.     else
  560.     { printf("error: stack full\n");
  561.       clear();
  562.       return(0);
  563.     }
  564.   }
  565.  
  566.  
  567.   double pop(void)
  568.   {
  569.     if (sp > 0)
  570.       return(val[--sp]);
  571.     else
  572.     { printf("error: stack empty\n");
  573.       clear();
  574.       return(0);
  575.     }
  576.   }
  577.  
  578.  
  579.   void clear(void)
  580.   {
  581.     sp = 0;
  582.   }
  583.  
  584.  
  585.  
  586.  
  587.   Figure 2: File STACK.C which contains the functions push(), pop() and
  588.   clear().
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.                                                                              
  599.  
  600.  
  601.  
  602.  
  603.                                                          What c-scope does  8
  604.  
  605.  
  606.   #include <stdio.h>
  607.  
  608.   #define NUMBER '0'
  609.   #define TOOBIG '9'
  610.  
  611.   int getop(char *s, int lim)
  612.   {
  613.     int i,c;
  614.  
  615.     while ((c = getc(stdin)) == ' ' || c == '\t' ||
  616.             c == '\n')
  617.       ;
  618.  
  619.     if (c != '.' && (c < '0' || c > '9'))
  620.       return(c);
  621.  
  622.     s[0] = c;
  623.     for (i=1; (c = getc(stdin)) >= '0' && c <= '9'; i++)
  624.       if (i < lim)
  625.         s[i] = c;
  626.     if (c == '.')
  627.     { if (i < lim)
  628.         s[i] = c;
  629.       for (i++; (c = getc(stdin)) >= '0' && c <= '9'; i++)
  630.         if (i < lim)
  631.           s[i] = c;
  632.     }
  633.  
  634.     if (i < lim)
  635.     { ungetc(c,stdin);
  636.       s[i] = '\0';
  637.       return(NUMBER);
  638.     }
  639.     else
  640.     { while (c != '\n' && c != EOF)
  641.         c = getc(stdin);
  642.       s[lim-1] = '\0';
  643.       return(TOOBIG);
  644.     }
  645.   }
  646.  
  647.  
  648.  
  649.  
  650.   Figure 3: File GETOP.C which contains function getop().
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.                                                                              
  659.  
  660.  
  661.  
  662.  
  663.                                                              Using c-scope  9
  664.  
  665.  
  666.  
  667.  
  668.  
  669.                                 3 Using c-scope
  670.  
  671.  
  672.  
  673.  
  674.   3.1 Installing c-scope
  675.  
  676.   Installation of c-scope couldn't be easier. The distribution diskette
  677.   contains the program CS.EXE and a file called READ.ME that you should check
  678.   for any last minute updates that did not make this manual.
  679.  
  680.         The distribution diskette is not copy protected so you can copy the
  681.   program to your hard disk--a good location would be the directory where you
  682.   keep your utilities. It should be a directory that is pointed to by your
  683.   PATH environment variable so that c-scope will be easy to use.
  684.  
  685.         It is also possible to use c-scope from a floppy diskette too. It is
  686.   quite small and doesn't require a lot of disk space so it is convenient to
  687.   use even from a diskette.
  688.  
  689.         In any event, don't execute the program from the distribution
  690.   diskette. Copy it to another disk and put the distribution diskette away in
  691.   a safe place.
  692.  
  693.  
  694.   3.2 Running c-scope
  695.  
  696.         c-scope may be used to analyze a single source file by typing
  697.  
  698.           cs program.c
  699.  
  700.   where program.c is the name of the source file. More typically it will be
  701.   used to analyze a program spread across numerous files. In this case you
  702.   just type
  703.  
  704.           cs
  705.  
  706.   c-scope looks in the current directory for a file called SOURCE.DAT. In
  707.   this file it expects to find the names of the files comprising the
  708.   program--one per line. Full filenames are required, and paths may be
  709.   included for source files not in the current directory. For instance, in
  710.   the example program in Section 2, SOURCE.DAT contained the following three
  711.   lines:
  712.  
  713.           getop.c
  714.           dcalc.c
  715.           stack.c
  716.  
  717.  
  718.                                                                              
  719.  
  720.  
  721.  
  722.  
  723.                                                             Using c-scope  10
  724.  
  725.  
  726.  
  727.   As the source files are processed, c-scope writes their names to stderr,
  728.   and the analysis is written to stdout which usually appears on your screen.
  729.   If you would rather have the reports in a file, use I/O redirection:
  730.  
  731.           cs > program.rpt
  732.  
  733.   This puts the output in a file called PROGRAM.RPT which can be printed or
  734.   edited.
  735.  
  736.         As mentioned above, the -e option will force c-scope to expand all
  737.   references to a function, e.g.,
  738.  
  739.           cs -e
  740.  
  741.  
  742.   3.2.1 Circular Function References
  743.         If your program is constructed in such a way that function calls form
  744.   a circuit, e.g., function a calls function b, which calls function c, which
  745.   calls function a again, then expanding all function references with the -e
  746.   option could potentially cause an infinite expansion.
  747.  
  748.         c-scope will detect such circuits and print [C] beside the function
  749.   name in the static calling tree where it was detected. If the -e option was
  750.   specified, c-scope will stop expansion at that point.
  751.  
  752.  
  753.   3.3 Ignoring functions
  754.  
  755.         Usually you will find with c-scope that many of the functions
  756.   referenced in a program belong to the C library. You may not be interested
  757.   in these functions, and may feel their inclusion clutters the output
  758.   needlessly. If so you may create a file called IGNORE.DAT, which c-scope
  759.   will read if it is present in the current directory.
  760.  
  761.         c-scope expects to find the names of functions, one per line, in
  762.   IGNORE.DAT. c-scope will ignore these functions when it generates its
  763.   output reports.
  764.  
  765.         For example, if you didn't want the references to the functions
  766.   printf, fprintf, strcpy and strcmp to appear in the reports, IGNORE.DAT
  767.   would contain
  768.  
  769.           printf
  770.           fprintf
  771.           strcpy
  772.           strcmp
  773.  
  774.   You may also include names of functions which are defined in your
  775.   source--not just C library function names.
  776.  
  777.  
  778.                                                                              
  779.  
  780.  
  781.  
  782.  
  783.                                                             Using c-scope  11
  784.  
  785.  
  786.  
  787.  
  788.   3.4 Function declarations
  789.  
  790.         When c-scope encounters a function name internal to another function
  791.   it determines if the reference is a declaration or a call by checking for
  792.   one of C's reserved storage class or type identifiers. However, if you have
  793.   declared a function that returns a DEFINEd or typedef'd result, c-scope
  794.   will not recognize it as a declaration and will treat it as a call. A
  795.   common example is:
  796.  
  797.           FILE *myopen();
  798.  
  799.   To avoid this problem, you can make sure all internal function declarations
  800.   have the extern class, i.e.,
  801.  
  802.           extern FILE *myopen();
  803.  
  804.   or, you can create a file called TYPES.DAT. This file will be read by
  805.   c-scope if present, and will be assumed to consist of type identifiers that
  806.   c-scope will add to its list of C keywords. In the above illustration,
  807.   TYPES.DAT would contain the line:
  808.  
  809.           FILE
  810.  
  811.   This problem does not occur for function declarations external to a
  812.   function.
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.                                                                              
  839.  
  840.  
  841.  
  842.  
  843.                                                                     Notes  12
  844.  
  845.  
  846.  
  847.  
  848.  
  849.                                     4 Notes
  850.  
  851.  
  852.   c-scope examines each source file in SOURCE.DAT looking for function names.
  853.   When it encounters one, it determines if the function name represents a
  854.   definition, a call, or an external or internal declaration.
  855.  
  856.         c-scope uses a knowledge of C program syntax to identify functions
  857.   and their context. It is not a compiler though, and some situations may
  858.   cause problems. These are discussed in this section.
  859.  
  860.  
  861.   4.1 Non-standard function types
  862.  
  863.         This was discussed in Section 3.4. c-scope doesn't recognize an
  864.   internal function declaration as such if it returns a type which is not one
  865.   of C's predefined types (int, float, double, char, etc. or pointers to
  866.          ___                                       these) and an implicitly defined storage class.
  867.  
  868.         You can remedy this by declaring the function to be of the extern
  869.   storage class (which is proper form but often left assumed for functions),
  870.   or by including the new type in TYPES.DAT.
  871.  
  872.         Note that all external function declarations are recognized as such,
  873.   regardless of the type.
  874.  
  875.  
  876.   4.2 Preprocessor
  877.  
  878.         The current version of c-scope ignores preprocessor lines. This means
  879.   it does not process include files (however, good style dictates that such
  880.   files should not contain executable code anyway).
  881.  
  882.         Macros are not expanded, so that functions which are referenced by
  883.   macros are not noticed by c-scope. Also, macros which take arguments are
  884.   not recognized as such, but are interpreted as external functions.
  885.  
  886.         Conditional compilation directives are ignored.
  887.  
  888.  
  889.   4.3 Function pointers
  890.  
  891.         c-scope does not deal properly with pointers to functions; for
  892.   example, in the following:
  893.  
  894.           main()
  895.           {
  896.  
  897.  
  898.                                                                              
  899.  
  900.  
  901.  
  902.  
  903.                                                                     Notes  13
  904.  
  905.  
  906.             char *(*fncn)();
  907.             char *a(void);
  908.             fncn = a;
  909.             printf ("this is %s\n",(*fncn)());
  910.           }
  911.  
  912.           char name[10];
  913.           char *a(void)
  914.           {
  915.             strcpy(name,"function A");
  916.             return(name);
  917.           }
  918.  
  919.   c-scope does not recognize (*fncn)() as a function call. Such calls should
  920.   be rewritten as fncn() which is permissible under the ANSI standard, where
  921.   the syntax for calls to functions and to functions specified by pointers is
  922.   allowed to be the same.
  923.  
  924.         Even with this change though, c-scope will only recognize that fncn()
  925.   has been called, and not that a() was indirectly called.
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.                                                                              
  959.  
  960.  
  961.  
  962.  
  963.                                                            Error messages  14
  964.  
  965.  
  966.  
  967.  
  968.  
  969.                                A Error messages
  970.  
  971.  
  972.   This section describes the error messages that c-scope may produce and
  973.   offers suggestions on how to remedy the problems they indicate.
  974.  
  975.                        ____        Invalid option -opt
  976.   A program option was specified that is not one of -e or -c.
  977.  
  978.                        ________        Unable to open filename
  979.   A source file was specified on the command line or in the file SOURCE.DAT
  980.   that cannot be opened--check for spelling mistakes, etc.
  981.  
  982.         Error--no main function
  983.   There is no main function in any of the source files; a static calling tree
  984.   will not be produced.
  985.  
  986.         Error - insufficient memory to proceed
  987.   c-scope was unable to allocate any more memory for its internal tables. The
  988.   more files, functions and function references your source files contain,
  989.   the more memory will be required. It is unlikely this error will ever
  990.   occur, but if it does, try to free up some memory in your system and try
  991.   again.
  992.  
  993.                                        ___        _  _____        Error--token too long (limit = nnn) line  n: token
  994.   A token was found in the source file that exceeds the internal limit. Most
  995.   likely due to a too-long literal character string--may result from an
  996.   unmatched ".
  997.  
  998.                                                       ___         Error - too many function references (limit = nnn)
  999.   The source files in SOURCE.DAT collectively call too many functions.
  1000.   Contact JAYAR Systems.
  1001.  
  1002.                                                    ___         Error - too many source functions (limit = nnn)
  1003.   The source files in SOURCE.DAT collectively contain too many functions.
  1004.   Contact JAYAR Systems.
  1005.  
  1006.         Unable to open source.dat and no arguments given
  1007.   You need to supply the name of a source file on the command line or have a
  1008.   file called SOURCE.DAT containing source file names in the current working
  1009.   directory.
  1010.  
  1011.                                        ___         Too many source files (limit = nnn)
  1012.   Too many source files were specified in SOURCE.DAT. Contact JAYAR Systems.
  1013.  
  1014.                                 ___         Too many types (limit = nnn)
  1015.   You have specified too many user types in TYPES.DAT. Contact JAYAR Systems.
  1016.  
  1017.  
  1018.                                                                              
  1019.  
  1020.  
  1021.  
  1022.  
  1023.                                                            Error messages  15
  1024.  
  1025.  
  1026.                                                    ___         Too many functions in ignore list (limit = nnn)
  1027.   You have specified too many function names to ignore in IGNORE.DAT. Contact
  1028.   JAYAR Systems.
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.                                                                              
  1079.  
  1080.  
  1081.  
  1082.  
  1083.                                                                   License  16
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.                                    B License
  1090.  
  1091.  
  1092.   This appendix contains important license information regarding the use of
  1093.   c-scope, Version 1.22. This information applies to individual users who
  1094.   wish to pass copies out to friends and associates.
  1095.  
  1096.         User Groups, Computer Clubs, Disk Vendors and Distributors,
  1097.   Subscription Services, Disk-of-the-Month Clubs, etc., should refer to the
  1098.   VENDOR.DOC file for complete information relating to them.
  1099.  
  1100.         BBS SYSOPs should refer to the SYSOP.DOC file for complete
  1101.   information relating to them.
  1102.  
  1103.         PLEASE! Show your support for Shareware by registering the programs
  1104.   you actually use. JAYAR Systems depends upon and needs your support. Thank
  1105.   you!
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.                                                                              
  1139.  
  1140.  
  1141.  
  1142.  
  1143.                                                        Trial Use License:  17
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.                              C Trial Use License:
  1150.  
  1151.  
  1152.   c-scope is NOT a public domain program. It is Copyright (C) 1991-96 by
  1153.   JAYAR Systems. All rights reserved.
  1154.  
  1155.         This software and accompanying documentation are protected by
  1156.   Canadian Copyright law and also by International Treaty provisions. Any use
  1157.   of this software in violation of Copyright law or the terms of this limited
  1158.   license will be prosecuted to the best of our ability. The conditions under
  1159.   which you may copy this software and documentation are clearly outlined
  1160.   below under "Distribution Restrictions".
  1161.  
  1162.         JAYAR Systems hereby grants you a limited license to use this
  1163.   software for evaluation purposes for a period not to exceed sixty (60)
  1164.   days. If you intend to continue using this software (and/or it's
  1165.   documentation) after the sixty (60) day evaluation period, you MUST make a
  1166.   registration payment to JAYAR Systems.
  1167.  
  1168.         Using this software after the sixty (60) day evaluation period,
  1169.   without registering the software is a violation of the terms of this
  1170.   limited license.
  1171.  
  1172.         Licensee shall not use, copy, rent, lease, sell, modify, decompile,
  1173.   disassemble, otherwise reverse engineer, or transfer the licensed program
  1174.   except as provided in this agreement. Any such unauthorized use shall
  1175.   result in immediate and automatic termination of this license.
  1176.  
  1177.         All rights not expressly granted here are reserved to JAYAR Systems.
  1178.  
  1179.         For information on registering your copy of c-scope see Appendix F,
  1180.   "How to Register."
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.                                                                              
  1199.  
  1200.  
  1201.  
  1202.  
  1203.                                             Limited Distribution License:  18
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.                         D Limited Distribution License:
  1210.  
  1211.  
  1212.   As the copyright holder for c-scope, JAYAR Systems authorizes distribution
  1213.   by individuals only in accordance with the following restrictions.
  1214.  
  1215.         (User Groups, Computer Clubs, Disk Vendors and Distributors,
  1216.   Subscription Services, Disk-of-the-Month Clubs, etc., should refer to the
  1217.   VENDOR.DOC file for complete information relating to them.)
  1218.  
  1219.         (BBS SYSOPs should refer to the SYSOP.DOC file for complete
  1220.   information relating to them.)
  1221.  
  1222.         Individuals are hereby granted permission by JAYAR Systems to copy
  1223.   the c-scope diskette for their own use (for evaluation purposes) or for
  1224.   other individuals to evaluate, ONLY when the following conditions are met.
  1225.  
  1226.         The c-scope package is defined as containing all the material listed
  1227.   in the PACKING.LST text file. If any files listed in the PACKING.LST text
  1228.   file, or the PACKING.LST file itself, are missing, then the package is not
  1229.   complete and distribution is forbidden. Please contact us to obtain a
  1230.   complete package suitable for distribution.
  1231.  
  1232.     o The c-scope package--including all related program files and
  1233.       documentation files--CANNOT be modified in any way and must be
  1234.       distributed as a complete package, without exception. The PACKING.LST
  1235.       text file contains a list of all files that are part of the c-scope
  1236.       package.
  1237.  
  1238.     o No price or other compensation may be charged for the c-scope package.
  1239.       A distribution cost may be charged for the cost of the diskette,
  1240.       shipping and handling, as long as the total (per disk) does not exceed
  1241.       $10.00.
  1242.  
  1243.     o The c-scope package CANNOT be sold as part of some other inclusive
  1244.       package. Nor can it be included in any commercial software packaging
  1245.       offer, without a written agreement from JAYAR Systems.
  1246.  
  1247.     o The PRINTED User's Guide may not be reproduced in whole or in part,
  1248.       using any means, without the written permission of JAYAR Systems. In
  1249.       other words, the disk-based documentation may not be distributed in
  1250.       PRINTED (hardcopy) form.
  1251.  
  1252.     o The c-scope package cannot be "rented" or "leased" to others.
  1253.  
  1254.     o Licensee shall not use, copy, rent, lease, sell, modify, decompile,
  1255.       disassemble, otherwise reverse engineer, or transfer the licensed
  1256.  
  1257.  
  1258.                                                                              
  1259.  
  1260.  
  1261.  
  1262.  
  1263.                                             Limited Distribution License:  19
  1264.  
  1265.  
  1266.       program except as provided in this agreement. Any such unauthorized use
  1267.       shall result in immediate and automatic termination of this license.
  1268.  
  1269.         All rights not expressly granted here are reserved to JAYAR Systems.
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.                                                                              
  1319.  
  1320.  
  1321.  
  1322.  
  1323.                                                   Definition of Shareware  20
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.                            E Definition of Shareware
  1330.  
  1331.  
  1332.         Shareware distribution gives users a chance to try software before
  1333.   buying it. If you try a Shareware program and continue using it, you are
  1334.   expected to register. Individual programs differ on details--some request
  1335.   registration while others require it, some specify a maximum trial period.
  1336.   With registration, you get anything from the simple right to continue using
  1337.   the software to an updated program with printed manual.
  1338.  
  1339.         Copyright laws apply to both Shareware and commercial software, and
  1340.   the copyright holder retains all rights, with a few specific exceptions as
  1341.   stated below. Shareware authors are accomplished programmers, just like
  1342.   commercial authors, and the programs are of comparable quality. (In both
  1343.   cases, there are good programs and bad ones!) The main difference is in the
  1344.   method of distribution. The author specifically grants the right to copy
  1345.   and distribute the software, either to all and sundry or to a specific
  1346.   group. For example, some authors require written permission before a
  1347.   commercial disk vendor may copy their Shareware.
  1348.  
  1349.         Shareware is a distribution method, not a type of software. You
  1350.   should find software that suits your needs and pocketbook, whether it's
  1351.   commercial or Shareware. The Shareware system makes fitting your needs
  1352.   easier, because you can try before you buy. And because the overhead is
  1353.   low, prices are low also. Shareware has the ultimate money-back
  1354.   guarantee--if you don't use the product, you don't pay for it.
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.                              ASP OMBUDSMAN POLICY
  1361.  
  1362.         This program is produced by a member of the Association of Shareware
  1363.   Professionals (ASP). ASP wants to make sure that the shareware principle
  1364.   works for you. If you are unable to resolve a shareware-related problem
  1365.   with an ASP member by contacting the member directly, ASP may be able to
  1366.   help. The ASP Ombudsman can help you resolve a dispute or problem with an
  1367.   ASP member, but does not provide technical support for members' products.
  1368.   Please write to the ASP Ombudsman at 545 Grover Road Muskegon, MI 49442 or
  1369.   send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536.
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.                                                                              
  1379.  
  1380.  
  1381.  
  1382.  
  1383.                                                           How to Register  21
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.                                F How to Register
  1390.  
  1391.  
  1392.   c-scope is a "shareware program" and is provided at no charge to the user
  1393.   for evaluation. Feel free to share it with your friends, but please do not
  1394.   give it away altered or as part of another system. The essence of
  1395.   "user-supported" software is to provide personal computer users with
  1396.   quality software without high prices, and yet to provide incentive for
  1397.   programmers to continue to develop new products. If you find this program
  1398.   useful and find that you are using c-scope and continue to use c-scope
  1399.   after a reasonable trial period, you must make a registration payment of
  1400.   US$24.00 (Cdn$28.00) to JAYAR Systems. The registration fee will license
  1401.   one copy for use on any one computer at any one time.
  1402.  
  1403.         When you register you receive the following:
  1404.  
  1405.     o You will get the latest version of c-scope,
  1406.  
  1407.     o The registered version of c-scope does not display a banner
  1408.       (registration reminder notice) when it runs,
  1409.  
  1410.     o You will get a typeset manual,
  1411.  
  1412.     o the registered version of c-scope generates two additional reports--a
  1413.       set of software complexity metrics and an inverse function reference or
  1414.       "called by" report. In the first the number of lines, statements,
  1415.       whiles, fors, switches and ifs are reported for each function. In the
  1416.       second, the functions that call each function in your program are
  1417.       listed; functions that are not called by any other function are also
  1418.       listed.
  1419.  
  1420.         You must treat this software just like a book. An example is that
  1421.   this software may be used by any number of people and may be freely moved
  1422.   from one computer location to another, so long as there is no possibility
  1423.   of it being used at one location while it's being used at another. Just as
  1424.   a book cannot be read by two different persons at the same time.
  1425.  
  1426.         Commercial users of c-scope must register and pay for their copies of
  1427.   c-scope within 30 days of first use or their license is withdrawn. Your
  1428.   registration fee purchases a single user license. If you need to use
  1429.   multiple copies, significant savings can be had by purchasing a site
  1430.   license rather than registering multiple individual copies. Even a two-user
  1431.   site license saves you money. See the file SITELICE.DOC for details.
  1432.  
  1433.         Anyone distributing c-scope for any kind of remuneration must first
  1434.   contact JAYAR Systems at the address given in DESCRIBE.DOC for
  1435.   authorization. This authorization is automatically granted to distributors
  1436.  
  1437.  
  1438.                                                                              
  1439.  
  1440.  
  1441.  
  1442.  
  1443.                                                           How to Register  22
  1444.  
  1445.  
  1446.   and vendors who are members of the Association of Shareware Professionals
  1447.   (ASP). See files VENDOR.DOC and SYSOP.DOC for details.
  1448.  
  1449.         You are encouraged to pass a copy of c-scope along to your friends
  1450.   for evaluation. Please encourage them to register their copy if they find
  1451.   that they can use it. All registered users will receive a copy of the
  1452.   latest version of the c-scope system.
  1453.  
  1454.         Note that c-scope is available for UNIX as well as for the DOS
  1455.   operating system. If you are ordering the DOS version, you may order a
  1456.   single-user UNIX version at the same time for only half price. If you want
  1457.   to order the UNIX version alone, or if it will be used in a multiuser or
  1458.   networked environment you must use the site license application form for
  1459.   ordering (see file SITELICE.DOC).
  1460.  
  1461.         The UNIX version is shipped as obfuscated C source code and will
  1462.   compile on most systems. Give us a call if you have any questions about
  1463.   this option.
  1464.  
  1465.         Send in the following form to register your copy of c-scope:
  1466.  
  1467.  
  1468.  
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.                                                                              
  1499.  
  1500.  
  1501.   REGISTRATION FORM
  1502.   Send to:  JAYAR Systems                  GST Registration Number:
  1503.             253 College Street             R124607193
  1504.             Suite 263
  1505.             Toronto, Ontario
  1506.             Canada   M5T 1R5
  1507.  
  1508.   Name       ___________________________________________
  1509.  
  1510.   Address    ___________________________________________
  1511.  
  1512.              ___________________________________________
  1513.  
  1514.              ___________________________________________
  1515.  
  1516.              ___________________________________________
  1517.  
  1518.   Telephone  __________________________
  1519.  
  1520.   +--------+------------------------+------------+------------+
  1521.   |Quantity| Product                | Each       |   Total    |
  1522.   +--------+------------------------+------------+------------+
  1523.   |        |                        |  US$24.00  |            |
  1524.   |        | c-scope                |     or     |            |
  1525.   |        |                        | Cdn$28.00  |            |
  1526.   +--------+------------------------+------------+------------+
  1527.   |        |single user UNIX version|1/2 of above|            |
  1528.   +--------+------------------------+------------+------------+
  1529.   |               Canadian residents add 7% GST  |            |
  1530.   +----------------------------------------------+------------+
  1531.   |                Ontario residents add 8% PST  |            |
  1532.   +----------------------------------------------+------------+
  1533.   |      Outside Canada/U.S.A.,   add shpg/hndlg |   $5.00    |
  1534.   +----------------------------------------------+------------+
  1535.   |                                       TOTAL  |            |
  1536.   +----------------------------------------------+------------+
  1537.  
  1538.   DISK FORMAT (check one): 5-1/4"DD [  ]   5-1/4"HD [  ]   3-1/2"HD [  ]
  1539.  
  1540.   Please remit by cheque (we will accept cheques in your local currency at
  1541.   the appropriate rate of exchange) or by money order.  We will accept your
  1542.   company's purchase order.  We also accept payment by Visa or Mastercard.
  1543.  
  1544.   P.O. Number  ______________________________________ (P.O. to follow)
  1545.  
  1546.        +------------------------------------------------------------------+
  1547.        | Note - Fill out the following ONLY if you are making payment by  |
  1548.        |        credit card.  You may also call (416) 751-5678 for credit |
  1549.        |        card registrations.                                       |
  1550.        |                                                                  |
  1551.        | Master Card [ ]  Visa [ ] Card Number ______ ______ _____ ______ |
  1552.        |                                                                  |
  1553.        | Name on the Card (print) _______________________________________ |
  1554.        |                                                                  |
  1555.        | Expires ____/____                                                |
  1556.        |                    Signature ___________________________________ |
  1557.        |                                                                  |
  1558.        +------------------------------------------------------------------+
  1559.